home *** CD-ROM | disk | FTP | other *** search
/ Aminet 2 / Aminet AMIGA CDROM (1994)(Walnut Creek)[Feb 1994][W.O. 44790-1].iso / Aminet / text / show / ppmore20.lzh / PPMore / PPMore.doc < prev    next >
Text File  |  1991-11-20  |  22KB  |  487 lines
  1.  
  2.  
  3.  
  4.                             PPMore 2.0 User Manual
  5.  
  6.                                  Oct 6, 1991
  7.  
  8.  
  9.  
  10. Preface
  11. =======
  12.  
  13. The programs and files in this distribution are freely distributable, but are
  14. also copyright (c) Nico François.  They may be freely distributed as long as
  15. no more than a nominal fee is charged to cover time and copying costs.
  16.    No commercial usage is permitted without written permission from the
  17. author.  Everything in this distribution must be kept together, in original
  18. unmodified form.
  19.    The above is generally known as freeware.
  20.  
  21.    If you have suggestions or remarks about this program, or if you find
  22. any bugs, please let me know.
  23.  
  24.    Write to the following address:
  25.  
  26.                                 Nico François
  27.                                 Corbielaan 13
  28.                                 B-3060 Bertem
  29.                                 BELGIUM
  30.  
  31.    PPMore 2.0 requires AmigaDOS Release 2 (Kickstart & Workbench 2.0) to run.
  32.  
  33.  
  34. Contents
  35. ========
  36.  
  37. 1. An introduction
  38.  
  39. 2. Usage
  40.  
  41. 3. Control
  42.  
  43. 4. Using PPMore from other programs
  44.  
  45.  
  46. 1. An introduction
  47. ==================
  48.  
  49. This program was written to complement one of my other utilities,
  50. PowerPacker (a command and data cruncher).  It is used to read normal ascii
  51. text files or text files crunched with PowerPacker.  The program itself is
  52. about 13K long and when you know you save about 60% when you crunch a text
  53. file, you can see that this could save a lot of space on your disks.
  54.  
  55.    PPMore was written as a more replacement (as you could have guessed :-),
  56. so I tried to keep the keyboard commands the same as well as adding some new
  57. ones.  There are two main differences between PPMore and More, PPMore uses
  58. gadgets and it always loads the complete file in memory (More only loads part
  59. of the file and will load the rest when needed).  If you can live with these
  60. differences, you can replace More with PPMore anywhere you want.
  61.  
  62.    PPMore uses 'powerpacker.library' and 'reqtools.library', so make sure
  63. these are present in your Libs: directory.  Double-click 'Install_libs' for
  64. an automatic installation.
  65.  
  66.    If you haven't got PowerPacker you are of course missing one of the main
  67. features of this program.  PowerPacker is available as shareware (up to
  68. version 2.3b) or as a commercial program (version 4.0a).  The commercial
  69. version offers several enhancements like 40 to 50 times faster crunching,
  70. overlay support, an ARexx port, and much more.
  71.  
  72.  
  73. 2. Usage
  74. ========
  75.  
  76. PPMore can be used in several different ways.
  77.  
  78. - First of all via the CLI:
  79.  
  80.    If you enter 'PPMore ?' you will get a standard AmigaDOS template.  Enter
  81. 'PPMore ??' for more information.  You use PPMore like this:
  82.  
  83.    PPMore [<file|dir>] [TABS n] [PUBSCREEN <name|@addr|@*>]
  84.                        [MEMVIEW m,l,f[,n]]
  85.  
  86.    If you provide a file the program will load and display it.  Files
  87. crunched using PowerPacker 2.0 or higher will be automatically decrunched by
  88. PPMore.  If the file was encrypted you will be prompted for the password.
  89.  
  90.    Options:
  91.  
  92.       TABS n     Select tabsize, default is 8.  Also see the Settings menu.
  93.       PUBSCREEN  Specify the public screen (by name) where PPMore should open
  94.                  its main window.  Note that only real public screens will
  95.                  be recognized, not any screen.  If you do not specify this
  96.                  option the default public screen will be used (normally
  97.                  the Workbench).
  98.  
  99.    The MEMVIEW option and other uses of the PUBSCREEN option are explained in
  100. section 4.
  101.  
  102.    PPMore can be made resident so it doesn't have to be loaded every time
  103. you use it, use the C: Resident command for this.  You can't make PPMore
  104. resident when it is crunched!!  The file is supplied as an uncrunched command
  105. file with the pure bit set.
  106.    If you enter PPMore without options, you will be presented with a file
  107. requester.  Entering PPMore with a directory instead of a file as an argument
  108. will also get you a file requester, but it will be positioned in the directory
  109. you specified.
  110.  
  111.    Examples:
  112.  
  113.      o PPMore DOCS:PPMore.doc TABS 4
  114.  
  115.          Load and display 'DOCS:PPMore.doc' and use a tabsize of 4 spaces.
  116.  
  117.      o PPMore PUBSCREEN "Public Screen" TABS=6 AUTO:
  118.  
  119.          Put up file requester (in directory AUTO:) and open window on
  120.        the public screen named 'Public Screen' (if found).  Quotes are
  121.        used to pass a screentitle with spaces.  Use tabsize of 6.
  122.  
  123.      o PPMore ppmore.doc.pp PUBSCREEN Workbench
  124.  
  125.          Load and display 'ppmore.doc.pp' on the Workbench screen, no
  126.        matter what the default public screen is.
  127.  
  128. - Via the WorkBench:
  129.  
  130.    There are three different ways of using PPMore via the workbench: you
  131. can set the default tool of the (crunched) text file to 'PPMore', you can
  132. single click the PPMore icon and then double click the text file icon or you
  133. can double-click the PPMore icon and pick a file using the file requester.
  134.  
  135.    You set the default tool by single clicking the icon of the text file
  136. and selecting 'Info' from the workbench menu.  You will get a window with
  137. several gadgets in it, click in the string gadget where it says 'Default
  138. tool' and enter 'PPMore'.  PPMore should be in the command path for this to
  139. work, otherwise you must enter the full path so Workbench can find it.  Last
  140. of all select the 'Save' gadget.
  141.  
  142.    Following tooltype is recognized by PPMore (in the text file's icon, not
  143. PPMore's icon):
  144.  
  145.      TABS=n  : Set tabsize for file (default 8).
  146.  
  147.  
  148. NOTE: - PPMore will add '.pp' to the filename when the file wasn't found.
  149.         This is very useful in the WorkBench enviroment: you can make an
  150.         icon for 'text.doc' but name the file 'text.doc.pp'.  Now the
  151.         WorkBench will show an icon with 'text.doc' as name, but if you
  152.         doubleclick it 'text.doc.pp' will be displayed.  (As long as there
  153.         is no 'text.doc' file in the directory!)
  154.       - After reading a file you can press 'L' to load a new file, instead of
  155.         quitting and restarting.
  156.       - In the AmigaDOS template ignore the /M modifier on FILE, PPMore does
  157.         not accept multiple file names (it was needed to let PPMore still
  158.         support the old command line format for compatibility).
  159.  
  160.  
  161. 3. Control
  162. ==========
  163.  
  164.    PPMore can be controlled by keyboard or by intuition gadgets.  To get a
  165. summary of the keyboard commands press <HELP>, the function of the gadgets
  166. shouldn't be hard to understand.
  167.  
  168.    A few notes on printing:
  169.  
  170.    o The printer.device has to be in the DEVS: directory for PPMore to be
  171.      able to print, you should also have correct preferences settings for
  172.      your printer.  Make especially sure the number of lines is correct.
  173.  
  174.    o You can continue to read the text when PPMore is printing (this IS a
  175.      multitasking computer! :-), you *CAN* quit when printing is still in
  176.      progress, printing will continue and all memory will be freed once it
  177.      is finished.
  178.  
  179.    PPMore has a settings menu that allows you to change most of its settings.
  180. You can save these settings, snapshot or unsnapshot PPMore's window.
  181.  
  182.    The settings menu allows you to switch the following things on/off:
  183.  
  184.    o Scroll Text:  This determines if text is scrolled or paged upon doing
  185.      a page up or down.  Note that the shifted keys/gadgets temporarily
  186.      reverse this switch.  By this I mean that if Space does a paged page
  187.      down, pressing Shift Space will do a scrolled page down.
  188.  
  189.    o Wrap Lines:  Line wrap mode determines how lines that are too long will
  190.      be displayed.  If it is on long lines will continue on the next line, if
  191.      it is off they will be cut off.  If a line is cut off an inverse '>'
  192.      will appear on the right edge of the window.
  193.  
  194.    o Line Numbers:  If this is on PPMore will display line number in the
  195.      title of its window instead of a percentage.
  196.  
  197.    You can also change the tab size and the window's font.  Any fixed width
  198. font will work.  'Snapshot Window' will remember PPMore's window position.
  199. 'Unsnapshot Window' will forget the position and will go back to the default
  200. behaviour of opening a window as large as the visible screen size.
  201.  
  202.  
  203. 4. Using PPMore from other programs
  204. ===================================
  205.  
  206.    If you are not a programmer you can skip this section.
  207.  
  208.    PPMore has two special options to make it possible to use it from other
  209. programs.  This way you don't have to include a text displayer in your
  210. program, you just execute PPMore with one (or all) of the following options:
  211.  
  212.    MEMVIEW mem,len,flags[,name]
  213.  
  214.      If you specify this option PPMore will not load a file but instead it
  215.    will display a chunk of memory.  You specify the memory addres and
  216.    length in the command line as well as some flags.  The current version
  217.    only has one flag: PPMORE_FREEMEM = bit 0 of the flag-word = 0x1.
  218.      When this flag is set PPMore will free the memory after it has
  219.    finished (using exec.library/FreeMem()), if it isn't set PPMore will
  220.    just exit and leave the memory alone.  This way your program can start
  221.    PPMore with the PPMORE_FREEMEM flag set and exit before PPMore has ended.
  222.    PPMore will then free the memory instead of your program.
  223.      The address, length and flags must be presented as HEX longwords
  224.    seperated by a comma.  These options can be followed by another comma
  225.    and a string to give the memory chunk a name, if this string is omited
  226.    PPMore will use the name 'memory'.
  227.  
  228.    PUBSCREEN @addr  or  PUBSCREEN @*
  229.  
  230.      Apart from the use of the PUBSCREEN option explained in section 2, you
  231.    can supply a '@' followed by a screen address in HEX or a '*'.  PPMore
  232.    will then open the main window on this screen.  If you specify a '*' the
  233.    frontmost screen will be used.
  234.  
  235.    Examples:
  236.  
  237.      o PPMore MEMVIEW "1A000,1D4E,0,my chunk"
  238.  
  239.          PPMore will open a window 'Listing of my chunk', start
  240.        displaying at address 0x1A000 and stop at address 0x1BD4E.  The
  241.        memory will not be freed after PPMore exits.  Note the use of
  242.        quotes to get a title with spaces in.
  243.  
  244.      o PPMore PUBSCREEN @c2d8a0 MEMVIEW 1A000,1D4E,1,memname
  245.  
  246.          Same as previous but now PPMore will free the memory chunk and
  247.        open the main window on the custom screen with the screen structure
  248.        on address 0xc2d8a0.
  249.  
  250.      o PPMore PUBSCREEN @* myfile
  251.  
  252.          Load and display the file 'myfile' and open window on the front
  253.        screen.
  254.  
  255. NOTE: - If you use PPMore on another screen that is not a public screen
  256.         PPMore will not check if the screen closes!  PPMore should always
  257.         finish before this screen is closed! (There is no problem when you
  258.         open the window on a public screen)
  259.       - Watch out when using these options, it is very easy to crash the Amiga
  260.         if you don't know what you are doing!  Using the PUBSCREEN with
  261.         the name of a public screen is of course 100% safe.
  262.       - The '-S' and '-@' options of older versions of PPMore are still
  263.         supported for compatibility, but you should no longer use them.
  264.  
  265.  
  266.                       As always, I hope you find this program useful!
  267.  
  268.  
  269.                               PROGRAM HISTORY:
  270.  
  271. *****************************************************************************
  272. VERSION 1.0
  273.  
  274.      First release.
  275.  
  276. *****************************************************************************
  277. VERSION 1.1
  278.  
  279.      '.pp' suffix added to filename when file not found, very useful in
  280.        WorkBench enviroment.
  281.      PPMore now also loads encrypted files. (PowerPacker 2.3a or higher)
  282.  
  283. *****************************************************************************
  284. VERSION 1.2
  285.  
  286.      Rewritten some routines in assembler, results in a slightly faster
  287.        and smaller PPMore.
  288.      Keyboard input improved. Autorepeat of keys is ignored so you can keep
  289.        on pressing <page down> without typing it 20 times ahead!
  290.      Gadget input also improved, now handles repeat.
  291.      PPMore now prompts for a filename when double-clicked from WorkBench.
  292.  
  293. *****************************************************************************
  294. VERSION 1.3
  295.  
  296.      PPMore can now be made resident and is reentrant. (provided PPMore is
  297.        not crunched)
  298.      Improved error reporting, the main window only opens when PPMore is
  299.        going to display the file.
  300.      File is checked to see if it is an ASCII (text) file.
  301.      Two new power-options for use of PPMore from other programs:
  302.        -@ to display memory, -S to open window on a custom screen.
  303.      Fast assembler search function added.
  304.      Display position is displayed in titlebar (percentage).
  305.      Goto n% function added, replaced 'Refresh' gadget with this function.
  306.      Decrunching is 15% faster.
  307.      'Exit PPMore' only selected when button is released on top of gadget.
  308.      NO bugs removed because none where found. :-)
  309.      Only about 700 bytes larger than version 1.2!
  310.  
  311. *****************************************************************************
  312. VERSION 1.4
  313.  
  314.      Bug fixed: PPMore 1.3 was not 100% pure, version 1.4 is!
  315.      ASCII check less strict (e.g. now allows files to contain a '©')
  316.      Another 300 bytes shorter than version 1.3 :-)
  317.  
  318. *****************************************************************************
  319. VERSION 1.5
  320.  
  321.      Bug fixed: search/goto window always opened on WorkBench screen.
  322.      Find previous also implemented.
  323.      Load a new file from within PPMore.
  324.      PPMore uses ARP file requester if arp.library is available.
  325.      Line count, as well as goto line.
  326.      Display position as percentage or line number.
  327.      Keypad = movement. (for PC-lovers, yek :-( )
  328.      PPMore now supports all keymaps!! I think especially german and french
  329.        Amiga users will be grateful for this.
  330.      Less than 600 bytes longer than version 1.4 (I love this :-D)
  331.  
  332. *****************************************************************************
  333. VERSION 1.5a
  334.  
  335.      Decrunching is 40% faster, this was a stupid mistake in 1.3 to 1.5,
  336.        I accidently used a slower instead of a faster decrunch routine :-(
  337.  
  338. *****************************************************************************
  339. VERSION 1.5b
  340.  
  341.      The Guru isn't with me lately, after using a slow decruncher in 1.3-1.5
  342.        by accident I now used a fast but faulty decruncher in 1.5a. It
  343.        sometimes didn't decrunch correctly, this has now been fixed. The
  344.        decruncher is still 40% faster than the 1.3-1.5 one. (and it's 2 bytes
  345.        shorter :^D )
  346.  
  347. *****************************************************************************
  348. VERSION 1.6
  349.  
  350.      Bugs in search fixed, didn't work correctly when used in large files and
  351.        sometimes didn't work at all :-(
  352.      Error output goes to the console when you start PPMore from the CLI,
  353.        WorkBench error reporting still in small window as before.
  354.      The ASCII check was made less strict (again).  I got a lot of complaints
  355.        from German users trying to display german documents, this should now
  356.        no longer be a problem.
  357.      If you deactivated the window when PPMore was loading PPMore would hang
  358.        until you resized its window, this has been fixed.  (Actually, I
  359.        worked around this problem, I think it was an Intuition bug :-)
  360.      PgUp, PgDn and the shifted arrow keys now do an immediate page up/down
  361.        without scrolling, SPACE and BS still scroll up/down.
  362.      Changed some things so PPMore runs better on Kickstart 2.0, next
  363.        version of PPMore will probably be a Kick 2.0 only version so I can
  364.        make use of all the new goodies of the new OS :^)
  365.  
  366. *****************************************************************************
  367. VERSION 1.6a
  368.  
  369.      Small update on special request.  Now possible to dump just the visible
  370.        page to the printer instead of the entire file.
  371.  
  372. *****************************************************************************
  373. VERSION 1.7
  374.  
  375.      No Kickstart 2.0 only version yet.  Changed some stuff so PPMore looks
  376.        best on Kick 2.0 and still runs on Kick 1.3.
  377.      Uses the all new powerpacker.library => shorter code :^D
  378.      Starting PPMore from the CLI with a directory as an argument now puts
  379.        up the requester positioned in that directory. Extremely useful once
  380.        you get used to this :^)
  381.      Small bug fixed in search routine, it sometimes missed an occurence.
  382.      PPMore filters out form-feeds and replaces them with <FORM FEED>.
  383.      If you are running Workbench 2.0 PPMore will use the asl.library
  384.        instead of the arp.library (for the filerequester).
  385.      Now fully supports system & screen fonts different than topaz 8.
  386.      Automatic refresh when you resize the window (only on Kick 2.0,
  387.        couldn't be done on 1.3 because of bug in console.device)
  388.      Used different technique to find workbench screen size, using
  389.        NormalDisplayRows no longer seemed to work on 2.0 ?!?!?
  390.  
  391. *****************************************************************************
  392. VERSION 1.8
  393.  
  394.      Nicer new-look 3D gadgets in window border for Kickstart 1.3.
  395.      Line wrap on/off implemented.  If switched off causes all lines to be
  396.        cut off at the right edge of the window.
  397.      Seemed that the asl requester no longer worked on the latest
  398.        Kickstart 2.0 (release V37). Fixed.
  399.      Asl requester doesn't show '.info' icon files.
  400.  
  401. *****************************************************************************
  402. VERSION 2.0
  403.  
  404.      Yep, an AmigaOS 2.0 only version.  Sorry to all the 1.2 & 1.3 users,
  405.        just consider this program yet another reason to upgrade :-)
  406.  
  407.      The filerequester from the arp.library is no longer used/supported.
  408.      PPMore now uses reqtools.library (also by moi) for its requesters.
  409.        Among other things this means a much better filerequester than
  410.        before (with a buffer).  Asl is no longer used, sorry Commodore :-)
  411.      Improved command line format, follows AmigaDOS standard (old command
  412.        line format is still supported for compatibility).
  413.      Workbench tooltypes supported (TABS=n).
  414.      PPMore will open its window on the default public screen.
  415.      The '.pp' suffix is removed from the filename in the window title.
  416.      Fully supports public screens with the PUBSCREEN option, file requester
  417.        will also appear on public screen.
  418.      PPMore will bring the screen it appears on to the front.
  419.      The user is now given the option to read all files, so it is possible
  420.        to force PPMore to display files it considers binary (non-ASCII).
  421.      Tabsize is user-definable, PPMore will expand tabs to up to 8 spaces.
  422.        Files with lots tabs (e.g. source codes) display much nicer now :^)
  423.      Printing has been considerably improved, PPMore now prints in pages
  424.        and puts a title with the filename (excluding path and '.pp') and the
  425.        page number at the top of each page (Page dumps will have no title).
  426.        Tabs are expanded to the same size as in the text window.  Also, it
  427.        is now possible to quit PPMore once printing has started, printing
  428.        will continue in the background.
  429.      Error reporting improved, PPMore will no longer open a small window for
  430.        error messages when loading. When started from CLI, errors are printed
  431.        on the console; when started from Workbench, a requester is used.
  432.      From Workbench, if you single-click PPMore and shift double-click a
  433.        drawer icon, PPShow will open up the filerequester in that drawer.
  434.      If you use 'PPMore <file>' or extend-select <file> from Workbench and
  435.        you invoke the filerequester, it will be positioned in the directory
  436.        <file> is in.
  437.      Directories are expanded to their full pathnames on startup.
  438.      You can now use CTRL-C to quit and CTRL-D to break scripts.
  439.      Bug & quirk fixes:
  440.        All gadgets and text now stay visible on a 1 bitplane screen.
  441.        Formfeeds are now replaced by an inverse L instead of <FORM FEED> and
  442.          may appear anywhere in the file, not just at the start of a line.
  443.        Page up/down without scrolling will no longer refresh window when at
  444.          top/bottom of file.
  445.        PPMore has always used one column less than was available, I finally
  446.          noticed this and fixed it (how come nobody saw this ? :-)
  447.        Keypad now really is movement, aside from PgUp, PgDn, Home and End,
  448.          you may now also use the arrows on the keypad.
  449.        PPMore now returns a returncode of 20 in case of an error or if ended
  450.          by CTRL-D.
  451.      Removed read in low memory when the close gadget was used.  Thanks to
  452.        the enforcer I was able to fix a VERY obscure bug :-)
  453.      PPMore now contains a version string.  Use 'Version PPMore' to display
  454.        the internal version number.
  455.      Shift 'Next Page' and 'Prev Page' now do an immediate page up/down
  456.        without scrolling, just like Shift Arrow Up, Shift Arrow Down.
  457.      Window has been changed to simple refresh, saves chip memory.
  458.      Added a Project menu with 'Load File...' and 'Quit' items.
  459.      A Settings menu has also been added to the window.  It allows you to
  460.        change and save several settings.
  461.      The position of the window can be snapshot (Settings menu).
  462.      Scrolling can be switched off (Settings menu), so 'Next Page',
  463.        'Prev Page', Space and Backspace do an immediate page up/down.
  464.        If scrolling is off the shifted gadgets/keypresses will page
  465.        with scrolling (instead of without).
  466.      The font used to print the text can be changed (in the Settings menu).
  467.      PPMore's window will only cover the visible portion of the screen, it
  468.        will no longer open a window that is as big as the whole screen.
  469.        This is only true if the window has NOT been snapshot.
  470.      Gadgets use a (private) boopsi image class, much nicer :-)
  471.  
  472. *****************************************************************************
  473.  
  474. PPMore 2.0 written by Nico François (Yes, Nico is my first name :-)
  475.            thanks to Holger Lubitz for the many bug reports :^) and all the
  476.                                    useful suggestions.
  477.  
  478. "Blood your hand on a cactus tree,
  479.  wipe it on your dress and send it to me." - The Pixies
  480.  
  481.  
  482. (c) 1991 Nico François
  483.  
  484.                                    //
  485.                        Thanks to \X/ Amiga for being the best computer ever!
  486.  
  487.